<!DOCTYPE html>
<html>
<head>
	<meta charset="utf-8">
	<meta name="viewport" content="width=device-width, initial-scale=1">

	<style type="text/css">
		@import url('../css/main.css');
	</style>

	<title>Writing a GRUB configuration file</title>
</head>

<body>
	<div class="section">
		<h1 id="pagetop">Writing a GRUB configuration file</h1>
			<p>
				This section is for those systems which use the GRUB payload.
				<b>If your system uses the depthcharge payload, ignore this section.</b>
			</p>
			<p>
				<a href="index.html">Back to index</a>
			</p>
	</div>

	<div class="section">

		<h1>Table of Contents</h1>
			<ul>
				<li>
					<a href="#example_modifications">Example modifications for <i>grubtest.cfg</i></a>
					<ul>
						<li><a href="#example_modifications_trisquel">Trisquel GNU/Linux-libre</a></li>
						<li><a href="#example_modifications_parabola">Parabola GNU/Linux-libre</a></li>
					</ul>
				</li>
			</ul>
			
	</div>

	<div class="section">
		<h2 id="example_modifications">Example modifications for <i>grubtest.cfg</i></h2>

		<p>
			These are some common examples of ways in which the grubtest.cfg file can be modified.
		</p>

		<div class="subsection">
			<h2>Obvious option: don't even modify the built-in grub.cfg</h2>
				<p>
					Use the menuentry that says something like <i>Search for GRUB outside CBFS</i>. Assuming that you 
					have a grub.cfg file at /boot/grub/ in your installed distro, this will generate a new menuentry in
					the GRUB menu. Use that to boot.
				</p>
				<p>
					Then do this as root:<br/>
					$ <b>cd /boot/grub/</b><br/>
					$ <b>ln -s grub.cfg libreboot_grub.cfg</b>
				</p>
				<p>
					After that, your system should then boot automatically.
				</p>
		</div>

		<div class="subsection">

			<h2>Trisquel with full disk encryption, custom partition layout</h2>
				<p>
					GRUB can boot from a symlink (or symlinks) pointing to your kernel/initramfs, whether from an unencrypted or encrypted /boot/. You
					can create your own custom symlink(s) but you have to manually update them when updating your kernel. This guide (not maintained by
					the libreboot project) shows how to configure Trisquel to automatically update that symlink on every kernel update.
					<a href="http://www.rel4tion.org/people/fr33domlover/libreboot-fix/">http://www.rel4tion.org/people/fr33domlover/libreboot-fix/</a>
				</p>
				<p>
					TODO: adapt those notes and put them here. The author said that it was CC-0, so re-licensing under GFDL shouldn't be a problem.
				</p>

		</div>

		<div class="subsection">
				<h3 id="example_modifications_trisquel">Trisquel GNU/Linux-libre</h3>

					<p>
						As an example, on my test system in /boot/grub/grub.cfg (on the HDD/SSD) I see for the main menu entry:
					</p>
					<ul>
							<li><b>linux	/boot/vmlinuz-3.15.1-gnu.nonpae root=UUID=3a008e14-4871-497b-95e5-fb180f277951 ro   crashkernel=384M-2G:64M,2G-:128M quiet splash $vt_handoff</b></li>
							<li><b>initrd	/boot/initrd.img-3.15.1-gnu.nonpae</b></li>
					</ul>

					<p>
						<b>ro</b>, <b>quiet</b>, <b>splash</b>, <b>crashkernel=384M-2G:64M,2G-:128M</b> and 
						<b>$vt_handoff</b> can be safely ignored.
					</p>

					<p>
						I use this to get my partition layout:<br/>
						$ <b>lsblk</b>
					</p>

					<p>
						In my case, I have no /boot partition, instead /boot is on the same partition as / on sda1. 
						Yours might be different. In GRUB terms, sda means ahci0. 1 means msdos1, or gpt1, depending 
						on whether I am using MBR or GPT partitioning. Thus, /dev/sda1 is GRUB is (ahci0,msdos1) or 
						(ahci0,gpt1). In my case, I use MBR partitioning so it's (ahci0,msdos1).
						'msdos' is a GRUB name simply because this partitioning type is traditionally used by MS-DOS. 
						It doesn't mean that you have a proprietary OS.
					</p>

					<p>
						Trisquel doesn't keep the filenames of kernels consistent, instead it keeps old kernels and 
						new kernel updates are provided with the version in the filename. This can make GRUB payload 
						a bit tricky. Fortunately, there are symlinks /vmlinuz and /initrd.img
						so if your /boot and / are on the same partition, you can set GRUB to boot from that. 
						These are also updated automatically when installing kernel updates from your distributions 
						apt-get repositories.
						<b>
							Note: when using <a href="http://jxself.org/linux-libre">jxself kernel releases</a>, 
							these are not updated at all and you have to update them manually.
						</b>
					</p>

					<p>
						For the GRUB payload grubtest.cfg (in the 'Load Operating System' menu entry), we therefore have (in this example):<br/>
						<b>set root='ahci0,msdos1'</b><br/>
						<b>linux /vmlinuz root=UUID=3a008e14-4871-497b-95e5-fb180f277951</b><br/>
						<b>initrd /initrd.img</b>
					</p>

					<p>
						Optionally, you can convert the UUID to its real device name, for example /dev/sda1 in this case.
						sdX naming isn't very reliable, though, which is why UUID is used for most distributions.
					</p>

					<p>
						Alternatively, if your /boot is on a separate partition then you cannot rely on the /vmlinuz and /initrd.img symlinks.
						Instead, go into /boot and create your own symlinks (update them manually when you install a new kernel update).<br/>
						$ <b>sudo -s</b> (or <b>su -</b>)<br/>
						# <b>cd /boot/</b><br/>
						# <b>rm -f vmlinuz initrd.img</b><br/>
						# <b>ln -s <u>yourkernel</u> ksym</b><br/>
						# <b>ln -s <u>yourinitrd</u> isym</b><br/>
						# <b>exit</b>
					</p>

					<p>
						Then your grubtest.cfg menu entry (for payload) becomes like that, for example if / was on sda2 and /boot was on sda1:<br/>
						<b>set root='ahci0,msdos1'</b><br/>
						<b>linux /ksym root=/dev/sda2</b><br/>
						<b>initrd /isym</b>
					</p>

					<p>
						There are lots of possible variations so please try to adapt.
					</p>

		</div>

		<div class="subsection">
			<h3 id="example_modifications_parabola">Parabola GNU/Linux-libre</h3>

				<p>
					You can basically adapt the above. Note however that Parabola does not keep old kernels still installed, and the file names 
					are always consistent, so you don't need to boot from symlinks, you can just use the real thing directly.
				</p>
		</div>

		<p>
			<a href="#pagetop">Back to top of page.</a>
		</p>

	</div>

	<div class="section">

		<p>
			Copyright &copy;  2014, 2015 Leah Rowe &lt;info@minifree.org&gt;<br/>
			Permission is granted to copy, distribute and/or modify this document
			under the terms of the GNU Free Documentation License, Version 1.3
			or any later version published by the Free Software Foundation;
			with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
			A copy of the license can be found at <a href="../gfdl-1.3.txt">../gfdl-1.3.txt</a>
		</p>

		<p>
			Updated versions of the license (when available) can be found at
			<a href="https://www.gnu.org/licenses/licenses.html">https://www.gnu.org/licenses/licenses.html</a>
		</p>

		<p>
			UNLESS OTHERWISE SEPARATELY UNDERTAKEN BY THE LICENSOR, TO THE
			EXTENT POSSIBLE, THE LICENSOR OFFERS THE LICENSED MATERIAL AS-IS
			AND AS-AVAILABLE, AND MAKES NO REPRESENTATIONS OR WARRANTIES OF
			ANY KIND CONCERNING THE LICENSED MATERIAL, WHETHER EXPRESS,
			IMPLIED, STATUTORY, OR OTHER. THIS INCLUDES, WITHOUT LIMITATION,
			WARRANTIES OF TITLE, MERCHANTABILITY, FITNESS FOR A PARTICULAR
			PURPOSE, NON-INFRINGEMENT, ABSENCE OF LATENT OR OTHER DEFECTS,
			ACCURACY, OR THE PRESENCE OR ABSENCE OF ERRORS, WHETHER OR NOT
			KNOWN OR DISCOVERABLE. WHERE DISCLAIMERS OF WARRANTIES ARE NOT
			ALLOWED IN FULL OR IN PART, THIS DISCLAIMER MAY NOT APPLY TO YOU.
		</p>
		<p>
			TO THE EXTENT POSSIBLE, IN NO EVENT WILL THE LICENSOR BE LIABLE
			TO YOU ON ANY LEGAL THEORY (INCLUDING, WITHOUT LIMITATION,
			NEGLIGENCE) OR OTHERWISE FOR ANY DIRECT, SPECIAL, INDIRECT,
			INCIDENTAL, CONSEQUENTIAL, PUNITIVE, EXEMPLARY, OR OTHER LOSSES,
			COSTS, EXPENSES, OR DAMAGES ARISING OUT OF THIS PUBLIC LICENSE OR
			USE OF THE LICENSED MATERIAL, EVEN IF THE LICENSOR HAS BEEN
			ADVISED OF THE POSSIBILITY OF SUCH LOSSES, COSTS, EXPENSES, OR
			DAMAGES. WHERE A LIMITATION OF LIABILITY IS NOT ALLOWED IN FULL OR
			IN PART, THIS LIMITATION MAY NOT APPLY TO YOU.
		</p>
		<p>
			The disclaimer of warranties and limitation of liability provided
			above shall be interpreted in a manner that, to the extent
			possible, most closely approximates an absolute disclaimer and
			waiver of all liability.
		</p>
		
	</div>

</body>
</html>
